home *** CD-ROM | disk | FTP | other *** search
/ IRIX 6.5 Complementary Applications 2004 February / SGI IRIX 6.5 Complementary Applications 2004 February.iso / dist / cde.idb / usr / dt / share / man / cat3 / XmGetPixmap.z / XmGetPixmap
Encoding:
Text File  |  2003-11-18  |  8.9 KB  |  199 lines
  1.  
  2.  
  3.  
  4.      XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaapppp((((3333XXXX))))           UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV           XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaapppp((((3333XXXX))))
  5.  
  6.  
  7.  
  8.      NNNNAAAAMMMMEEEE
  9.       _X_m_G_e_t_P_i_x_m_a_p -    A pixmap caching function that generates a
  10.       pixmap, stores it in a pixmap    cache, and returns the pixmap
  11.  
  12.      SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.       #include <Xm/Xm.h>
  14.  
  15.       Pixmap XmGetPixmap (ssssccccrrrreeeeeeeennnn,,,, iiiimmmmaaaaggggeeee____nnnnaaaammmmeeee,,,, ffffoooorrrreeeeggggrrrroooouuuunnnndddd,,,, bbbbaaaacccckkkkggggrrrroooouuuunnnndddd)
  16.            _S_c_r_e_e_n     *ssssccccrrrreeeeeeeennnn;
  17.            _c_h_a_r     *iiiimmmmaaaaggggeeee____nnnnaaaammmmeeee;
  18.            _P_i_x_e_l     ffffoooorrrreeeeggggrrrroooouuuunnnndddd;
  19.            _P_i_x_e_l     bbbbaaaacccckkkkggggrrrroooouuuunnnndddd;
  20.  
  21.      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  22.       _X_m_G_e_t_P_i_x_m_a_p uses the parameter data to perform a lookup in
  23.       the pixmap cache to see if a pixmap has already been
  24.       generated that matches the data.  If one is found, a
  25.       reference count is incremented and the pixmap    is returned.
  26.       Applications should use _X_m_D_e_s_t_r_o_y_P_i_x_m_a_p when the pixmap is
  27.       no longer needed.
  28.  
  29.       If a pixmap is not found, iiiimmmmaaaaggggeeee____nnnnaaaammmmeeee is used to perform a
  30.       lookup in the    image cache.  If an image is found, it is used
  31.       to generate the pixmap, which    is then    cached and returned.
  32.  
  33.       If an    image is not found, iiiimmmmaaaaggggeeee____nnnnaaaammmmeeee is used as a filename,
  34.       and a    search is made for either an xpm pixmap    file or    an _X_1_0
  35.       or _X_1_1 bitmap    file. If it is found, the file is read,
  36.       converted into an image, and cached in the image cache.  The
  37.       image    is then    used to    generate a pixmap, which is cached and
  38.       returned.
  39.  
  40.       If iiiimmmmaaaaggggeeee____nnnnaaaammmmeeee    has a leading slash (/), it specifies a    full
  41.       pathname, and    _X_m_G_e_t_P_i_x_m_a_p opens the file as specified.
  42.       Otherwise, iiiimmmmaaaaggggeeee____nnnnaaaammmmeeee    specifies a filename.  In this case,
  43.       _X_m_G_e_t_P_i_x_m_a_p looks for    the file along the following search
  44.       paths, specified by _X_M_I_C_O_N_S_E_A_R_C_H_P_A_T_H or _X_M_I_C_O_N_B_M_S_E_A_R_C_H_P_A_T_H
  45.       depending on the type    of display, _X_B_M_L_A_N_G_P_A_T_H    and a default
  46.       search path, which varies depending on whether or not    the
  47.       _X_A_P_P_L_R_E_S_D_I_R environment variable is set.  The    order of the
  48.       search, is _X_M_I_C_O_N_S_E_A_R_C_H_P_A_T_H or _X_M_I_C_O_N_B_M_S_E_A_R_C_H_P_A_T_H first,
  49.       _X_B_M_L_A_N_G_P_A_T_H second, _X_A_P_P_L_R_E_S_D_I_R third, and finally the
  50.       vendor default search    path (see below), until    either the
  51.       file is found    or the paths are all visited.
  52.  
  53.       Both the environment variables _X_M_I_C_O_N_S_E_A_R_C_H_P_A_T_H and
  54.       _X_M_I_C_O_N_B_M_S_E_A_R_C_H_P_A_T_H specify a search path for xpm pixmap and
  55.       X bitmap files.  _X_m_G_e_t_P_i_x_m_a_p uses _X_M_I_C_O_N_S_E_A_R_C_H_P_A_T_H on    a
  56.       color    display    and _X_M_I_C_O_N_B_M_S_E_A_R_C_H_P_A_T_H on a monolithic one.
  57.       The type of the display is determined    automatically through
  58.       the use of Xm/ColorObj.  So _X_M_I_C_O_N_S_E_A_R_C_H_P_A_T_H should consist
  59.       of a path where locations of xpm files precede those of
  60.  
  61.  
  62.  
  63.      Page 1                        (printed 11/11/03)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaapppp((((3333XXXX))))           UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV           XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaapppp((((3333XXXX))))
  71.  
  72.  
  73.  
  74.       bitmap files,    and _X_M_I_C_O_N_B_M_S_E_A_R_C_H_P_A_T_H should maintain a
  75.       search path in favor of bitmap files.    These two search paths
  76.       are new in CDE Motif and will    be in Motif 2.0. The
  77.       _X_B_M_L_A_N_G_P_A_T_H environment variable, which is here for backward
  78.       compatibility    with Motif 1.x,    specifies a search path    only
  79.       for X    bitmap files.  All these variables can contain the
  80.       substitution field %B, where the iiiimmmmaaaaggggeeee____nnnnaaaammmmeeee argument to
  81.       _X_m_G_e_t_P_i_x_m_a_p is substituted for %B.  They can also contain
  82.       the substitution fields accepted by _X_t_R_e_s_o_l_v_e_P_a_t_h_n_a_m_e.  The
  83.       substitution field %T    is always mapped to _b_i_t_m_a_p_s, and %S is
  84.       always mapped    to NULL.
  85.  
  86.       If neither _X_M_I_C_O_N_S_E_A_R_C_H_P_A_T_H (_X_M_I_C_O_N_B_M_S_E_A_R_C_H_P_A_T_H if
  87.       monolithic) nor _X_B_M_L_A_N_G_P_A_T_H is set but the environment
  88.       variable _X_A_P_P_L_R_E_S_D_I_R is set, the following pathnames are
  89.       searched:
  90.             %B
  91.             $XAPPLRESDIR/%L/bitmaps/%N/%B
  92.             $XAPPLRESDIR/%l/bitmaps/%N/%B
  93.             $XAPPLRESDIR/bitmaps/%N/%B
  94.             $XAPPLRESDIR/%L/bitmaps/%B
  95.             $XAPPLRESDIR/%l/bitmaps/%B
  96.             $XAPPLRESDIR/bitmaps/%B
  97.             $HOME/bitmaps/%B
  98.             $HOME/%B
  99.             /usr/lib/X11/%L/bitmaps/%N/%B
  100.             /usr/lib/X11/%l/bitmaps/%N/%B
  101.             /usr/lib/X11/bitmaps/%N/%B
  102.             /usr/lib/X11/%L/bitmaps/%B
  103.             /usr/lib/X11/%l/bitmaps/%B
  104.             /usr/lib/X11/bitmaps/%B
  105.             /usr/include/X11/bitmaps/%B
  106.  
  107.       If none of the above paths is    set, the following pathnames
  108.       are searched:
  109.             %B
  110.             $HOME/%L/bitmaps/%N/%B
  111.             $HOME/%l/bitmaps/%N/%B
  112.             $HOME/bitmaps/%N/%B
  113.             $HOME/%L/bitmaps/%B
  114.             $HOME/%l/bitmaps/%B
  115.             $HOME/bitmaps/%B
  116.             $HOME/%B
  117.             /usr/lib/X11/%L/bitmaps/%N/%B
  118.             /usr/lib/X11/%l/bitmaps/%N/%B
  119.             /usr/lib/X11/bitmaps/%N/%B
  120.             /usr/lib/X11/%L/bitmaps/%B
  121.             /usr/lib/X11/%l/bitmaps/%B
  122.             /usr/lib/X11/bitmaps/%B
  123.             /usr/include/X11/bitmaps/%B
  124.  
  125.       These    paths are defaults that    vendors    may change.  For
  126.  
  127.  
  128.  
  129.      Page 2                        (printed 11/11/03)
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.      XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaapppp((((3333XXXX))))           UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV           XXXXmmmmGGGGeeeettttPPPPiiiixxxxmmmmaaaapppp((((3333XXXX))))
  137.  
  138.  
  139.  
  140.       example, a vendor may    use different directories for
  141.       /_u_s_r/_l_i_b/_X_1_1 and /_u_s_r/_i_n_c_l_u_d_e/_X_1_1.
  142.  
  143.       The following    substitutions are used in these    paths:
  144.  
  145.       %_B   The image name, from the    iiiimmmmaaaaggggeeee____nnnnaaaammmmeeee argument.
  146.  
  147.       %_N   The class name of the application.
  148.  
  149.       %_L   The display's language string.
  150.  
  151.       %_l   The language component of the display's language
  152.            string.
  153.  
  154.       Parameter descriptions are listed below:
  155.  
  156.       ssssccccrrrreeeeeeeennnn
  157.            Specifies the display screen on which the pixmap    is to
  158.            be drawn.  The depth of the pixmap is the default depth
  159.            for this    screen.
  160.  
  161.       iiiimmmmaaaaggggeeee____nnnnaaaammmmeeee
  162.            Specifies the name of the image to be used to generate
  163.            the pixmap
  164.  
  165.       ffffoooorrrreeeeggggrrrroooouuuunnnndddd
  166.            Combines    the image with the ffffoooorrrreeeeggggrrrroooouuuunnnndddd color to create
  167.            the pixmap if the image referenced is a bit-per-pixel
  168.            image
  169.  
  170.       bbbbaaaacccckkkkggggrrrroooouuuunnnndddd
  171.            Combines    the image with the bbbbaaaacccckkkkggggrrrroooouuuunnnndddd color to create
  172.            the pixmap if the image referenced is a bit-per-pixel
  173.            image
  174.  
  175.      RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEE
  176.       Returns a pixmap when    successful; returns
  177.       _X_m_U_N_S_P_E_C_I_F_I_E_D__P_I_X_M_A_P if the image corresponding to the
  178.       iiiimmmmaaaaggggeeee____nnnnaaaammmmeeee cannot be found.
  179.  
  180.      RRRREEEELLLLAAAATTTTEEEEDDDD IIIINNNNFFFFOOOORRRRMMMMAAAATTTTIIIIOOOONNNN
  181.       _X_m_D_e_s_t_r_o_y_P_i_x_m_a_p(_3_X), _X_m_G_e_t_P_i_x_m_a_p_B_y_D_e_p_t_h(_3_X),
  182.       _X_m_I_n_s_t_a_l_l_I_m_a_g_e(_3_X), and _X_m_U_n_i_n_s_t_a_l_l_I_m_a_g_e(_3_X).
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.      Page 3                        (printed 11/11/03)
  196.  
  197.  
  198.  
  199.